/*
 * Copyright (C) 2010 Imavis Srl
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published
 * by the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package com.imavis.avimuxer;

import java.io.Closeable;
import java.io.IOException;
import java.util.Date;

/**
 * Wraps raw media data into a container format and writes them to disk.
 * <p>
 * A {@code Muxer} can be obtained by calling the
 * {@link MuxerBuilder#open(java.io.File)} method of a
 * {@link MuxerBuilder} instance.
 * <p>
 * A {@code Muxer} instance can be used only once. After the {@link #close()}
 * method is called, the instance cannot be opened again.
 *
 * @author Andrea Gualano
 */
public interface Muxer extends Closeable {
    /**
     * Writes one frame or packet to the output file.
     * <p>
     * The timestamp, if available, may be used to compute stream metadata,
     * such as the frame rate.
     *
     * @param data  the raw media data.
     * @param timestamp  the frame timestamp or {@code null}
     * @throws IOException if an I/O error occurs (the output file may be
     * invalid)
     */
    public void write(byte[] data, Date timestamp) throws IOException;

    /**
     * Closes the output file and releases any resources associated
     * with this muxer.
     * <p>
     * If this method is not called, or throws an exception, the resulting file
     * may be invalid.
     *
     * @throws IOException if an I/O error occurs (the output file may be
     * invalid)
     */
    @Override
    public void close() throws IOException;

    /**
     * Returns the current length of the output file.
     * <p>
     * This may include cached data not yet written to the file, such as AVI
     * indices.
     *
     * @return the current length of the output file (in bytes).
     */
    public long length();
}
